home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / dev / lang / pcq12b.lzh / Include / Utils / BuildMenu.i < prev    next >
Text File  |  1990-08-27  |  4KB  |  110 lines
  1. {
  2.     BuildMenu.i (of PCQ Pascal)
  3.  
  4.     These routines provide a simplified interface to the Amiga's
  5. menu system similar to the one in AmigaBASIC, as I recall.  The
  6. price you pay for this situation is, of course, flexibility, but
  7. for many menu systems the plain text will suffice.
  8.  
  9.     In order to use these routines, first create a window somehow.
  10. Then call InitializeMenu, passing your valid window pointer.
  11. Remember, the window must be open already.
  12.     Then, call NewMenu("Menu Name") with any name you like in order
  13. to set up your first menu.  Then call NewItem("name", 'N') for each
  14. menu item you want to create.  You must call NewMenu before you
  15. call NewItem, and if you don't want a keyboard equivalent of the
  16. menu item, pass in '\0' (null).
  17.     If you want sub-items atached to your menu item, you can call
  18. NewSubItem with the same parameters as NewItem.  Note that you have
  19. to call NewItem at least once before you can call NewSubItem.
  20.     Also note that the order is significant.  If you switch the order
  21. of two menu item definitions, for example, they will appear in the
  22. opposite order in the menu.  Also, all menu items hang off the most
  23. recently defined menu.  Finally, note that these routines define only
  24. one menu strip at a time.
  25.  
  26.     Once you've got all that done, you call AttachMenu to allow the
  27. user to see and use the menu strip.  Then you'll have to monitor the
  28. IDCMP port of the window (window^.UserPort) for MENUPICK_f messages,
  29. which you can decifer with MenuNum() and ItemNum().  See the Intuition
  30. manual for details.
  31.     If you want to remove the menu from the window, you can call
  32. DetachMenu, but as long as you don't free the memory (see below) you
  33. can reattach the menu later by calling AttachMenu again.  You can also
  34. ghost various parts of the menu using OnMenu() and OffMenu(), but
  35. you'll have to see the Intuition manual to explain how.
  36.     To free up the memory associated with a menu you can call
  37. DisposeMenu.  If you haven't detached your menu the machine will
  38. crash, sooner or later.  You don't have to free the memory, since
  39. the termination code will do it for you.
  40.     You must detach your menu before closing the window.
  41.  
  42.     The source code for these routines is under Runtime/Extras
  43.  
  44. }
  45.  
  46. {$I "Include:Intuition/Intuition.i" for WindowPtr }
  47.  
  48. Procedure DisposeMenu;
  49.     External;
  50. {
  51.     Free the memory used by the menu strip.  Be sure the menu
  52.     is not currently displayed, or havoc will ensue.
  53. }
  54.  
  55. Procedure InitializeMenu(w : WindowPtr);
  56.     External;
  57. {
  58.     Set up the BuildMenu system will some useful defaults.  w must
  59.     point to a valid, open window.
  60. }
  61.  
  62. Procedure NewMenu(str : String);
  63.     External;
  64. {
  65.     Add a new menu to the menu strip.  You must call InitializeMenu
  66.     before this, and you must call this at least once before you call
  67.     NewItem or NewSub.
  68. }
  69.  
  70. Procedure NewItem(name : String; comm : Char);
  71.     External;
  72. {
  73.     Add an item to the previously defined menu.  You must call
  74.     NewMenu before you call this.  'name' is the text to print
  75.     in the box, and 'comm' is the keyboard equivalent.  If there
  76.     isn't a keyboard equivalent, use '\0' (zero byte).
  77.  
  78.     If you pad out all the menu item names to the same number of
  79.     characters (using spaces at the end), the user will have an
  80.     easier time using the menu.
  81. }
  82.  
  83. Procedure NewSubItem(name : String; comm : Char);
  84.     External;
  85. {
  86.     Add a sub-menu to the current menu item.  You must call NewItem
  87. before you call this.  The parameters and caveats are the same as
  88. NewItem.
  89. }
  90.  
  91. Procedure AttachMenu;
  92.     External;
  93. {
  94.     Attach the menu strip you've been designing to the window you
  95.     specified in your call to InitializeMenu.  This hands the structure
  96.     over to Intuition, which does all the real work.
  97. }
  98.  
  99. Procedure DetachMenu;
  100.     External;
  101. {
  102.     Remove the menu from the window.  This doesn't deallocate the memory
  103.     or anything traumatic like that.  You can, in fact, reattach the menu
  104.     later by calling AttachMenu.  In order to block the user's access to
  105.     the menu it is generally better to use OnMenu() and OffMenu(),
  106.     especially when you only want to block a few items.
  107.  
  108.     You must call this routine before closing a window.
  109. }
  110.